home *** CD-ROM | disk | FTP | other *** search
/ Freelog 22 / freelog 22.iso / Prog / Djgpp / GPC2952B.ZIP / doc / gpc / bugs < prev    next >
Encoding:
Text File  |  2001-02-08  |  13.8 KB  |  317 lines
  1. This file was generated automatically from support.texi.
  2. DO NOT CHANGE THIS FILE MANUALLY!
  3.  
  4. Note: This file is the `README' file of the `test' directory in the GPC
  5. source distribution, _and_ the file `BUGS' in GPC binary distributions.
  6.  
  7. The GPC Test Suite
  8. ******************
  9.  
  10. Here you can find information on where to find the most up-to-date
  11. information about GPC, how you can get support (professional or
  12. voluntary), how to use GPC's Test Suite, and how to report new bugs you
  13. might encounter.
  14.  
  15. If you have problems with GNU Pascal, please read the relevant sections
  16. of the GPC Manual. The most current version of the manual is available
  17. at `http://agnes.dida.physik.uni-essen.de/~gnu-pascal/gpc-doc.html' for
  18. online browsing.  You can also download the complete manual in HTML
  19. format (tar.gz) (`gpc-html.tar.gz' on GPC's WWW home page).  The manual
  20. is also available in DVI format (gzipped) (`gpc.dvi.gz' on GPC's WWW
  21. home page) and PostScript format (gzipped) (`gpc.ps.gz' on GPC's WWW
  22. home page) for printing.
  23.  
  24. If the manual doesn't help you, here is what we recommend you to do:
  25.  
  26.    * Check the GPC FAQ (see the file `FAQ' or the GPC Manual)
  27.  
  28.    * Join the GPC Mailing List
  29.  
  30.    * Look in the Mailing List Archives
  31.  
  32.    * Ask in a newsgroup
  33.  
  34.    * Get individual support for GPC
  35.  
  36.    * Find out how to report GPC bugs
  37.  
  38.    * If you have GPC sources, learn how to run the Test Suite to test
  39.      your bugs reported
  40.  
  41. The GPC Mailing List
  42. ====================
  43.  
  44. There is a mailing list devoted to GNU Pascal. You can write to the
  45. mailing list, e.g. if you have problems installing GPC or if you found
  46. a problem with GPC (please see *Note Reporting Bugs::). You can also
  47. use it to discuss suggestions for improving GPC and, most welcome, to
  48. offer your help or contribute code, documentation or other work. Mails
  49. to the list should be in English.
  50.  
  51. To subscribe to the mailing list, send the command
  52.      subscribe gpc your@email.address
  53. in the body of a mail to <majordomo@gnu.de> (*not* to `gpc@gnu.de'!).
  54. The subject is ignored. (Please replace `your@email.address' with your
  55. real email address.) For more info, send a line `help' to
  56. <majordomo@gnu.de>.
  57.  
  58. You can send a message to the mailing list by sending email to the list
  59. address <gpc@gnu.de> as if it were a person.
  60.  
  61. To leave the mailing list, send the command
  62.      unsubscribe gpc your@email.address
  63. to <majordomo@gnu.de>.
  64.  
  65. There is also a (low-traffic) announce list, <gpc-announce@gnu.de> that
  66. you can subscribe to stay up-to-date. To subscribe to the list, write
  67. an email with
  68.      subscribe gpc-announce your@email.address
  69. in the body to <majordomo@gnu.de>. If you like to announce a
  70. contribution, a service or an event related to GPC, you are invited to
  71. post to this list rather than `gpc@gnu.de', but please don't use the
  72. announce list for questions or discussions. Please note that all mail
  73. sent to the announce list is forwarded to the regular list, so you
  74. won't have to subscribe to both lists if you don't want to miss
  75. anything.
  76.  
  77. The GPC Mailing List Archives
  78. =============================
  79.  
  80. Perhaps your problem was already discussed on the list. There is a
  81. searchable archive of the mailing list on the WWW. It can be browsed or
  82. searched at `http://www.gnu.de/archive/wilma.cgi/gpc'.
  83.  
  84. The archive of the GPC announcement list is at
  85. `http://www.gnu.de/archive/wilma.cgi/gpc-announce'.
  86.  
  87. _Note:_ Currently, the search option is working fine. If you find it
  88. broken, please email me at <anja@drewitz.de>. Please don't mail a copy
  89. to the GPC list because I let procmail move all mails with `To: gpc...'
  90. and `Cc: gpc...' to a separate folder and would not see your mail for a
  91. long time. -- Anja
  92.  
  93. This archive starts in June 1999. For older messages, see:
  94.  
  95.      `ftp://agnes.dida.physik.uni-essen.de/gnu-pascal/misc/gpc-list-1998.gz'
  96.      (513 kB)
  97.      `ftp://agnes.dida.physik.uni-essen.de/gnu-pascal/misc/gpc-list-1997.gz'
  98.      (995 kB)
  99.      `ftp://agnes.dida.physik.uni-essen.de/gnu-pascal/misc/gpc-list-1996.gz'
  100.      (154 kB)
  101.      `ftp://agnes.dida.physik.uni-essen.de/gnu-pascal/misc/gpc-list-1995.gz'
  102.      (42 kB)
  103.  
  104. There is also a HTML version of these older archives at
  105. `http://www.iula.upf.es/altres/pub/gpc/list2html/gpclist.htm'.
  106.  
  107. Newsgroups relevant to GPC
  108. ==========================
  109.  
  110. To get support, you can also ask the Usenet newsgroups for help.  There
  111. are several Pascal related newsgroups, but none is dedicated just to
  112. GNU Pascal, so use the one which is most appropriate for your problem.
  113. For general Pascal questions, we recommend the following one:
  114.  
  115. `news://comp.lang.pascal.misc'       Pascal in general and ungrouped
  116.                                      Pascals.
  117.  
  118. Pascal syntax related questions may be appropriate in:
  119.  
  120. `news://comp.lang.pascal.ansi-iso'   Pascal according to ANSI and ISO
  121.                                      standards.
  122.  
  123. The next newsgroup is a haven for beginners, answering questions that
  124. would apply to almost any Pascal. However, if you have a GPC-specific
  125. question don't post there - use the GPC mailing list.  And when in
  126. doubt use the GPC mailing list.
  127.  
  128. `news://comp.lang.pascal.borland'    Borland Pascal questions.
  129.  
  130. Don't forget to give back what you have obtained. None of us is getting
  131. money for answering your questions (unless you pay us by yourself).
  132. Please do your part by answering the questions of others instead.
  133.  
  134. Where to get individual support for GPC
  135. =======================================
  136.  
  137. GPC is free software and comes *without any warranty*.
  138.  
  139. If you want to get professional support, you can hire an individual or
  140. a company for providing such a service.
  141.  
  142. G-N-U GmbH (http://www.g-n-u.de) is doing large parts of the
  143. development of GNU Pascal. This company offers special support for GPC
  144. and can be contacted at <info@g-n-u.de>.
  145.  
  146. More generally, to find a company or an individual who offers support
  147. and other consulting services for free software, look into the GNU
  148. Service Directory (http://www.gnu.org/prep/service.html).
  149.  
  150. If the compiler crashes...
  151. ==========================
  152.  
  153. If the compiler crashes, you have discovered a bug. A reliable compiler
  154. never crashes. To help the maintainers fix this bug, it is important
  155. that you send us a problem report.
  156.  
  157. If you're on Unix, you can find out where the compiler crashed if you
  158. enable coredumps, then load the compiler (`gpc1') plus the core file in
  159. the debugger (`gdb /your_path_here/gpc1 core'), then type `backtrace'
  160. to get a stacktrace. Include this stacktrace in your bug report.
  161.  
  162. How to report GPC bugs
  163. ======================
  164.  
  165. If you encounter a bug with GPC, please check whether it is one of the
  166. known bugs. If not, please report it to the GNU Pascal mailing list.
  167. That way, they always reach the maintainers. Please note the following
  168. points.
  169.  
  170.    * Please send a description of the problem. Try to give as much
  171.      information as possible, with the full text of any error messages
  172.      encountered, or a description of how some output varies from the
  173.      expected output. Always specify the operating system type with
  174.      version and the machine type (try `uname -a' if unsure) as well as
  175.      the version of GPC as printed by `gpc -v'.
  176.  
  177.    * A good article on submitting bug reports can be found at either
  178.      `http://www.chiark.greenend.org.uk/~sgtatham/bugs.html' or
  179.      `http://freshmeat.net/news/2000/02/26/951627540.html'
  180.  
  181.  
  182. If the problem is with the compiler itself, not an installation problem
  183. or something like this, please provide a test program to reproduce the
  184. problem, and note the following hints. You can also contribute test
  185. programs for features that are working in GPC to ensure they will not
  186. break in future releases.
  187.  
  188.    * The test program should be as short as possible, but *by all
  189.      means*, please send a *complete* program and *make sure* that it
  190.      still reproduces the problem before you send it. Too often, users
  191.      have sent code which contained obvious syntax errors far before
  192.      the actual problem, or just code fragments we could only make wild
  193.      guesses about. This is unproductive for us and doesn't help you
  194.      get your problem solved.
  195.  
  196.  
  197. The preferred form for test programs is the form that the automated GPC
  198. Test Suite understands. Please, if at all possible, send your test
  199. programs in this form which should be easy to do, so we won't have to
  200. waste our time to bring them into this form, and can concentrate on
  201. fixing the problem.
  202.  
  203.    * The file containing the main program must contain the keyword
  204.      `program' (case-insensitively) to be recognized by the testing
  205.      script. Other files, which can contain units or modules or data
  206.      needed by the program, must not contain the word `program'.
  207.  
  208.    * Since the Test Suite must run under very ... nah ... strange
  209.      operating systems, too, file names must be distinguished in their
  210.      first eight characters (case-insensitively) and should not contain
  211.      anything but letters, numbers, hyphens, underscores and a single
  212.      dot. The extension must be `.pas' to be recognized by the testing
  213.      script. Furthermore, any ancillary files (units, modules,
  214.      includes, data files) should not be longer than "8+3" characters.
  215.      It is often a good idea to use your name, nickname or initials
  216.      followed by a number as the file name.
  217.  
  218.    * The test program, when run, should produce a line of output
  219.      consisting of the string `OK' (followed by a newline) if
  220.      everything went as expected, and something else (e.g. `failed',
  221.      possibly followed by the reason of failure) if something went
  222.      wrong.
  223.  
  224.    * However, if the program is intended to check whether GPC catches an
  225.      (intentional) error in the program, place the string `WRONG'
  226.      somewhere in the test program, preferably in a comment in the line
  227.      that contains the intentional error, and make the program output
  228.      `failed' or something like this if it does compile mistakenly.
  229.  
  230.  
  231. The following special features of the testing script may be helpful for
  232. constructing tests:
  233.  
  234.    * If the expected output is something else than `OK', place it in a
  235.      file `<basename>.out' (where `<basename>' is the name of the test
  236.      program without the `.pas' extension).
  237.  
  238.    * If the test program expects some input, place it in a file
  239.      `<basename>.in'. It will automatically be redirected to the
  240.      program's standard input.
  241.  
  242.    * If the test needs some special flags to be given to the GPC command
  243.      line, place them in a comment preceded by `FLAG', e.g.:
  244.  
  245.           (* FLAG --extended-pascal -Werror *)
  246.  
  247.    * The source file name of the test program will be passed as the
  248.      first command-line argument to the test program run.
  249.  
  250.    * If a test needs to be run in a special way, you can accompany the
  251.      program with a script `<basename>.run' that will do the actual
  252.      test after the test program was compiled. This script will be run
  253.      by `sh' (regardless of its first line). In order to be portable,
  254.      it should only use standard tools. The source file name of the test
  255.      program will be passed as the first command-line argument to the
  256.      run script in this case. The compiled file is always called
  257.      `a.out'.
  258.  
  259.    * If a test needs to be compiled in a special way (e.g., to decide
  260.      whether to skip the test), place the commands in a script
  261.      (preferably called `<basename>.cmp'), and put the file name of the
  262.      script (without directory) in a comment preceded by `COMPILE-CMD:'
  263.      into the source of the test program. The compile script will be
  264.      run *instead* of any other action for this test program, so it
  265.      gives you maximum flexibility to do whatever you need to do. This
  266.      script will be run by `sh' (regardless of its first line). In
  267.      order to be portable, it should only use standard tools.  The
  268.      first command-line argument to the compile script will be the
  269.      compiler to use, including all options. The second argument will be
  270.      the source file name of the test program. For some typical tests,
  271.      there are standard compile scripts, e.g. `i386.cmp' which will
  272.      skip the test unless run on an i386 compatible processor. This is
  273.      necessary, e.g., when testing assembler code. Of course, it's still
  274.      better to avoid having to use such scripts when possible.
  275.  
  276.  
  277. Running the GPC Test Suite
  278. ==========================
  279.  
  280. _Note:_ If you have installed a GPC binary distribution, you usually
  281. don't have the Test Suite installed (you can download the GPC source
  282. distribution to get it, however), so this section does not apply to
  283. you. Still, you can find in the section `Contributing Tests to the Test
  284. Suite' how to report GPC bugs in the form of new test programs so we
  285. can fix them as fast as possible.
  286.  
  287. The files in the test directory and subdirectories are for testing GPC
  288. only and should not be of any other use.
  289.  
  290. Note: A few of the tests do not make sense on all systems. They are
  291. equipped with checks and will be skipped if they find the system not
  292. suitable. Skipped tests do *not* indicate a GPC bug, unless you have a
  293. reason to be sure that the particular test should make sense on your
  294. system.
  295.  
  296.    * To run the whole Test Suite, type `make' in the test directory (or
  297.      `make check' in the `p' object directory after building GPC).
  298.  
  299.    * The output will show all errors encountered (hopefully none) and
  300.      tests skipped, and finally display a summary giving the number of
  301.      successful, failed and skipped tests. Any failed test indicates a
  302.      bug in GPC which should be reported to the GPC mailing list,
  303.      <gpc@gnu.de>. Don't forget to mention the operating system you ran
  304.      the test on and any other relevant information about what you did.
  305.  
  306.    * You can also type `make pascal.check-long' to get a long output
  307.      which is a sequence of file names followed by `OK' for successful
  308.      tests, `SKIPPED' for skipped tests (both in capital letters), and
  309.      anything else for failed tests.
  310.  
  311.    * To run only some of the tests, you can type something like `make
  312.      MASK="foo[1-7]*.pas"' or `make MASK="foo42.pas" pascal.check-long'.
  313.  
  314.    * To clean up after running the tests, type `make clean'.
  315.  
  316.  
  317.